QuickTime 4 Reference

Vector QT Atom Container

A vector QT atom container specifies the characteristics of a QuickTime vector. The container contains atoms for paths and can also contain atoms that specify attributes of the paths, such as their color. For more information about QT atom containers, see "QuickTime Atoms" (page 47) .

To render paths, QuickTime traverses the atoms in the container in order. When it finds an atom for a path, it draws the path using the current attribute values. When it finds an atom for an attribute, the new attribute value replaces the previous value of the attribute. If QuickTime has not found an atom for a particular attribute before drawing a path, it uses the default value for the attribute.

All values in a vector QT atom container must be aligned on long-word boundaries and stored in big endian format.

A vector QT atom container can contain any of the following atoms. Atoms that are required are noted, as are atoms that must occur in a particular position within the container.

kCurveAntialiasControlAtom
Specifies whether subsequent paths in the vector data stream are drawn using antialiasing. Antialiasing is a technique in which edges of the path that do not fall on pixel boundaries are drawn by alpha blending the color of the path with the color of the background. The alpha values take into account errors introduced by the pixelization of the shape and give edges a smoother appearance. Antialiasing slightly slows the drawing of pixels, and it may be desirable to disable it when maximum drawing speed is required.

Legal values for this atom are
- 0 Enables antialiasing
- 0xFFFFFFFF Disables antialiasing
The data type of the value is long , and the size of the atom is sizeof(long) .

The default value is 0xFFFFFFFF .

This atom is optional.
kCurveARGBColorAtom
Specifies the color for subsequent paths in the vector data stream. Each of the color values (alpha, red, green, and blue) is an unsigned short integer. For most applications, the alpha value should be set to 0xFFFF .

The data type of the value is ARGBColor , and the size of the atom is sizeof(ARGBColor) .

The default value specifies black with an alpha value of 0xFFFF .

This atom is optional.
kCurveEndAtom
Specifies the end of the vector data stream.

The size of the atom is 0 .

This atom is required, and it must be at the end of the vector data stream.
kCurveFillTypeAtom
Specifies the fill type for subsequent paths in the vector data stream. For more information about fill types, see "Shape Fill" .

Legal values for this atom are
- gxNoFill = 0 Nothing is drawn
- gxOpenFrameFill Shape is framed or stroked along outline.
- gxFrameFill Shape is framed or stroked along outline.
- gxClosedFrameFill Shape is framed, open ends closed off.
- gxHollowFill Shape is framed, open ends closed off.
- gxEvenOddFill Shape is filled with even odd rule.
- gxSolidFill Shape is filled with even odd rule.
- gxWindingFill Shape is filled using winding rule.
- gxInverseEvenOddFill Area outside of shape is filled.
- gxInverseSolidFill Area outside of shape is filled.
- gxInverseFill Area outside of shape is filled.
- gxInverseWindingFill Area outside of winding is filled.
The data type of this atom is long , and the size of the atom is sizeof(long) .

The default value is gxEvenOddFill .

This atom is optional.
kCurveGradientAngleAtom

Specifies the gradient angle for subsequent linear gradients in the QT atom container. This allows the use of a linear gradient that begins at any part of the path rather than just at the top. The value defines the angle, in degrees, to rotate the linear gradient. For example, 0.0 specifies a top-to-bottom gradient, 90.0 specifies a right-to-left gradient, 180.0 specifies a bottom-to-top gradient, and 270.0 specifies a left-to-right gradient.

The data type of this atom is Fixed , and the size of the atom is sizeof(Fixed) .

The default value is 0.0 .

This atom is optional.

kCurveGradientOffsetAtom
Specifies the offset for subsequent gradients in the QT atom container. For circular gradients, this specifies the top left offset from the path being drawn. For linear gradients, it is the offset from the center of the rotated gradient line.

The data type of this atom is gxPoint , and size of this atom is sizeof(gxPoint) .

The default value is no offset.

This atom is optional.
kCurveGradientRadiusAtom

Specifies the radius, in pixels, of subsequent circular gradients in the QT atom container. This controls the positioning of the outside color in a circular gradient, which you can use to make a large section of the path be that outermost color.

The data type of this atom is Fixed , and the size of the atom is sizeof(Fixed) .

The default value is 0 , which results in no circular gradient being drawn.

This atom is required to draw a circular gradient. The value has no effect on a linear gradient.

kCurveGradientRecordAtom

Specifies the gradient fill colors for subsequent gradients in the QT atom container or, if there is no data, specifies to disable gradient fills for subsequent paths. If there is data, it consists of two or more GradientColorRecord structures that specify gradient fill colors. Each of these structures contains the following fields:

thisColor An ARGBColor value that specifies a color.
endingPercentage A Fixed value that specifies the position in the gradient, expressed as a value between 0.0 and 1.0 , at which to use the color. The value 0.0 specifies the beginning of the gradient, and the value 1.0 specifies the end.

Two GradientColorRecord structures are required in kCurveGradientRecordAtom atoms that contain data: one for 0.0 , which specifies the top or outside color of the gradient, and one for 1.0 , which specifies the bottom or centermost color used in the gradient. The data can include any number of additional GradientColorRecord structures. When QuickTime fills paths using the gradient, it uses a continuum of colors between the specified values.

The data type of this atom is GradientColorRecord , and the size of the atom is sizeof(GradientColorRecord)*count , where count is the number of GradientColorRecord structures in the atom's data.

The default is no data, which specifies to disable gradient fills for subsequent paths.

This atom is optional.

kCurveGradientTypeAtom

Specifies the type of subsequent gradients in the QT atom container. Legal values are:

kLinearGradient Specifies a linear gradient.
kCircularGradient Specifies a circular gradient.

By default, a linear gradient is filled from the top of the path to the bottom in a continuous line of colors. A circular gradient is drawn with a series of overlapping circles to form a burst pattern.

The data type of this atom is long , and the size of the atom is sizeof(long).

The default value is kLinearGradient , which specifies a linear gradient.

This atom is optional.

kCurveJoinAttributesAtom
Specifies the type of join for subsequent paths in the vector data stream with sharp angles, as described in "Joins" . When two lines in a polygonal path meet, there are several ways of resolving the intersection of their edge. Legal values are:
- gxSharpJoin Specifies a pointed elbow.
- gxCurveJoin Specifies a curved elbow.
- gxLevelJoin Specifies a cut-off elbow (no join).
The data type of this atom is gxJoinAttribute , and the size of the atom is sizeof(gxJoinAttribute).

The default value is gxSharpJoin .

This atom is optional.
kCurveMinimumDepthAtom

Specifies the minimum bit depth for drawing subsequent paths in the vector data stream. If the bit depth of the display device is less than the bit depth specified by the kCurveMinimumDepthAtom atom, the path is rendered into an offscreen buffer with the minimum bit depth and then transferred to the screen. This value must be at least 16 for most transfer modes. If the quality of a dithered image is unsatisfactory, increasing the kCurveMinimumDepthAtom value to 32 may improve the result.

The data type of this atom is long , and the size of the atom is sizeof(long) .

There is no default value; by default, the bit depth of the output is not changed.

The kCurveMinimumDepthAtom atom is optional.

If the kCurveMinimumDepthAtom atom is included, it must be first atom in the QT atom container.

kCurveMiterLimitAtom

Specifies the miter limit for subsequent paths in the vector data stream that include a sharp angle, such a polygons and triangles, as described in "Joins" . The value of this atom is multiplied by the current pen thickness (this is the value of the most recent kCurvePenThicknessAtom atom in the vector data stream or, if there is no kCurvePenThicknessAtom atom in the stream, the default value 1.0 ). The resulting value specifies the maximum number of points (1/72 of an inch) away from the ends at which the join can be drawn. The constant gxPositiveInfinity specifies that the join should be as sharp as necessary.

This value applies only to framed paths (those for which the kCurveFillTypeAtom value is gxOpenFrameFill or gxClosedFrameFill ).

The data type of this atom is Fixed , and the size of the atom is sizeof(Fixed) .

The default value is 1 .

This atom is optional.

kCurvePathAtom

Specifies a path to draw. The data for the path in contained in a gxPaths structure, which can contain up to 32767 contours, each of which may contain up to 32767 points. Each point may be located on or off the curve, with the curve describing a quadratic Bezier. The vectors in the contours are drawn together, obeying the intersection rules for the fill type, if any.

The data type of this atom is gxPaths , and the size of the atom is sizeof(gxPaths) + n, where n is (number of points) * sizeof(gxPoint).

This atom is required.

kCurvePenThicknessAtom
For subsequent paths in the vector data stream that are framed, specifies the thickness of the stroke for the frame, in points (1/72 of an inch). The center-frame attribute is set for the stroke, as described in "Pen Placement" .

This value applies only to framed paths (those for which the kCurveFillTypeAtom value is gxOpenFrameFill or gxClosedFrameFill ).

0 is an illegal value for this atom.

The data type of this atom is Fixed , and the size of the atom is sizeof(Fixed) .

The default value is 1.0 .

This atom is optional.
kCurveTransferModeAtom

Specifies the transfer mode for drawing paths. For information about transfer modes, see "Transfer Modes" .

The data type of this atom is gxTransferMode , and the size of the atom is sizeof(gxTransferMode) .

The default is to draw paths without a transfer mode.

This atom is optional.